home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / il / ilSemaphore.z / ilSemaphore
Encoding:
Text File  |  2002-10-03  |  8.8 KB  |  199 lines
  1.  
  2.  
  3.  
  4. iiiillllSSSSeeeemmmmaaaapppphhhhoooorrrreeee((((3333))))     IIIImmmmaaaaggggeeeeVVVViiiissssiiiioooonnnn LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll     iiiillllSSSSeeeemmmmaaaapppphhhhoooorrrreeee((((3333))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      iiiillllSSSSeeeemmmmaaaapppphhhhoooorrrreeee - provides semaphore services
  10.  
  11. IIIINNNNHHHHEEEERRRRIIIITTTTSSSS FFFFRRRROOOOMMMM
  12.      This is a base class and therefore has no inheritance.
  13.  
  14. HHHHEEEEAAAADDDDEEEERRRR FFFFIIIILLLLEEEE
  15.      #include <il/ilSemaphore.h>
  16.  
  17. CCCCLLLLAAAASSSSSSSS DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  18.      This class is an interface to the user-mode semaphore services and
  19.      provides tools for synchronizing access to shared resources. One can use
  20.      ilSemaphore to coordinate the way parallel threads of execution access
  21.      shared memory and other shared resources.
  22.  
  23.      Semaphores take a nonnegative integer value. A positive semaphore value
  24.      corresponds to a free lock in that it does not obstruct the continued
  25.      execution of a thread. A zero-valued semaphore corresponds to a set lock
  26.      in that it suspends or blocks the continued execution of a thread. The
  27.      thread remains blocked until another thread increments the semaphore
  28.      counter value.
  29.  
  30.      To use _i_l_S_e_m_a_p_h_o_r_e to control access to shared resources, the threads
  31.      should "get" a semaphore before using the resource. To get a semaphore,
  32.      one can use the ddddeeeecccc(((()))) function or the -- operator, both of which
  33.      decrement the semaphore counter (perform a P operation). If the semaphore
  34.      counter was positive before the P operation, the thread uses the
  35.      resource. When the thread is done with the resource, one can use the
  36.      _i_n_c() function or the ++ operator to increment (perform V operation) the
  37.      semaphore counter.
  38.  
  39.      If the value of the semaphore counter is zero when the P operation is
  40.      attempted, the system suspends the thread until the semaphore counter is
  41.      incremented by another thread performing a V operation.
  42.  
  43.      The semaphore count can be interpreted in the following way: if it is
  44.      greater than zero, there are that many resources available, namely that
  45.      many processes can use the _d_e_c() function and not block.  An allocated
  46.      semaphore is freed when the destructor is invoked.
  47.  
  48. CCCCLLLLAAAASSSSSSSS MMMMEEEEMMMMBBBBEEEERRRR FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNN SSSSUUUUMMMMMMMMAAAARRRRYYYY
  49.      CCCCoooonnnnssssttttrrrruuuuccccttttoooorrrr
  50.  
  51.           ilSemaphore(int val=1)
  52.  
  53.      SSSSeeeemmmmaaaapppphhhhoooorrrreeee sssseeeerrrrvvvviiiicccceeeessss
  54.  
  55.           int dec(int wait=TRUE)
  56.           int inc()
  57.           int operator=(int val)
  58.           int operator++()
  59.           int operator--()
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. iiiillllSSSSeeeemmmmaaaapppphhhhoooorrrreeee((((3333))))     IIIImmmmaaaaggggeeeeVVVViiiissssiiiioooonnnn LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll     iiiillllSSSSeeeemmmmaaaapppphhhhoooorrrreeee((((3333))))
  71.  
  72.  
  73.  
  74.           int set(int val)
  75.  
  76.  
  77. FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNN DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNNSSSS
  78.      iiiillllSSSSeeeemmmmaaaapppphhhhoooorrrreeee(((())))
  79.  
  80.           ilSemaphore(int val=1)
  81.  
  82.  
  83.           The constructor allocates a semaphore and initializes its count to
  84.           the value specified by _v_a_l. The semaphore that is allocated is a
  85.           blocking semaphore - if the semaphore is unavailable, the caller
  86.           blocks.
  87.  
  88.           A _v_a_l of 0 implies no available resources, and the first process
  89.           that attempts a P operation (by _d_e_c() or --) blocks.  This can be
  90.           viewed as a synchronizing semaphore, since the goal is to always
  91.           have a process block until another has completed an operation that
  92.           the first process requires.  Positive values for _v_a_l can be used for
  93.           tracking a collection of resources.  The simplest case of a value of
  94.           1 implements the common mutual exclusion semaphore, where one and
  95.           only one process is permitted through a semaphore at a time.  Values
  96.           greater than one imply that up to _v_a_l resources can be
  97.           simultaneously used, but requests for more than _v_a_l resources cause
  98.           the calling process to block until a resource comes free (by a
  99.           process holding a resource performing an _i_n_c() or ++).
  100.  
  101.           The _i_l_S_e_m_a_p_h_o_r_e instantiation fails if there is no memory available
  102.           to allocate the _i_l_S_e_m_a_p_h_o_r_e object or if _v_a_l is less than zero or
  103.           greater than 30000; in this case the program will be killed with an
  104.           assertion failure.
  105.  
  106.      ddddeeeecccc(((())))
  107.  
  108.           int dec(int wait=TRUE)
  109.  
  110.  
  111.           If _w_a_i_t is TRUE, this function performs a simple P operation on the
  112.           semaphore, blocking if necessary, and returns only when the calling
  113.           thread has acquired the semaphore. If _w_a_i_t is FALSE, the semaphore
  114.           is acquired if currently free; otherwise, zero is immediately
  115.           returned. Upon successful completion, a 1 is returned. A zero is
  116.           returned for platforms that do not support multiprocessing.
  117.  
  118.      iiiinnnncccc(((())))
  119.  
  120.           int inc()
  121.  
  122.  
  123.           This function performs a simple V operation, that is, it increments
  124.           the value of the semaphore. The first process (if any) waiting for
  125.           the semaphore is awakened. Upon successful completion, a 1 is
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. iiiillllSSSSeeeemmmmaaaapppphhhhoooorrrreeee((((3333))))     IIIImmmmaaaaggggeeeeVVVViiiissssiiiioooonnnn LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll     iiiillllSSSSeeeemmmmaaaapppphhhhoooorrrreeee((((3333))))
  137.  
  138.  
  139.  
  140.           returned. A zero is returned for platforms that do not support
  141.           multiprocessing.
  142.  
  143.      ooooppppeeeerrrraaaattttoooorrrr ====
  144.  
  145.           int operator=(int val)
  146.  
  147.  
  148.           This convenience operator performs the same function as the _s_e_t()
  149.           function described below, that is, it initialize the semaphore, with
  150.           the count of the semaphore set to _v_a_l. A value of zero is returned
  151.           on successful completion.
  152.  
  153.      ooooppppeeeerrrraaaattttoooorrrr ++++++++
  154.  
  155.           int operator++()
  156.  
  157.  
  158.           This convenience operator performs the same function as the _i_n_c()
  159.           function described above, that is, it increments the value of the
  160.           semaphore.
  161.  
  162.      ooooppppeeeerrrraaaattttoooorrrr --------
  163.  
  164.           int operator--()
  165.  
  166.  
  167.           This convenience operator performs the same function as the _d_e_c()
  168.           function described above, with _w_a_i_t set to TRUE.
  169.  
  170.      sssseeeetttt(((())))
  171.  
  172.           int set(int val)
  173.  
  174.  
  175.           This function initializes the semaphore and the count of the
  176.           semaphore is set to _v_a_l. For more information on _v_a_l, see the
  177.           constructor description above. The initialization fails if _v_a_l is
  178.           less than zero or greater than 30000. A zero is returned on
  179.           successful completion. A zero is also returned if the platform does
  180.           not support multiprocessing.
  181.  
  182. NNNNOOOOTTTTEEEESSSS
  183.      Refer to the _I_m_a_g_e_V_i_s_i_o_n _L_i_b_a_r_y _P_r_o_g_r_a_m_m_i_n_g _G_u_i_d_e for more details.
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.